; Document what happens when 'display' and 'invisible' props clash

* doc/lispref/display.texi (Replacing Specs, Overlay Properties)
(Invisible Text): Document that 'invisible' is ignored when
'display' property covers the same text.  (Bug#76658)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 8b1847cc4dc57b93624f71ed0bd5fcb339044071..95b17032a74970def407fa5f7dd27c753e4eb251 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1210,6 +1210,12 @@ The function is called with two arguments: the first is the overlay, and
 the second is @code{nil} to make the overlay visible, or @code{t} to
 make it invisible again.
 
+@cindex invisible text, and display properties
+  The @code{invisible} property is ignored in text that is covered by a
+@dfn{replacing} @code{display} property, because such @code{display}
+properties skip the text without processing its properties.
+@xref{Replacing Specs}.
+
 @node Selective Display
 @section Selective Display
 @c @cindex selective display   Duplicates selective-display
@@ -1918,7 +1924,9 @@ same as in the unhighlighted text.
 This property activates various features that change the
 way text is displayed.  For example, it can make text appear taller
 or shorter, higher or lower, wider or narrower, or replaced with an image.
-@xref{Display Property}.
+@xref{Display Property}.  Note that, if the @code{display} property is a
+@dfn{replacing} one (@pxref{Replacing Specs}), the @code{invisible}
+property of the same overlay will be ignored.
 
 @kindex help-echo @r{(overlay property)}
 @item help-echo
@@ -1981,8 +1989,11 @@ conventions are the same as for the @code{modification-hooks} functions.
 @kindex invisible @r{(overlay property)}
 @item invisible
 The @code{invisible} property can make the text in the overlay
-invisible, which means that it does not appear on the screen.
-@xref{Invisible Text}, for details.
+invisible, which means that it does not appear on the screen.  However,
+if the text covered by the overlay has a @dfn{replacing} @code{display}
+property, the @code{invisible} property will be ignored, because a
+replacing @code{display} property skips the text without examining its
+properties.  @xref{Invisible Text}, for details.
 
 @kindex intangible @r{(overlay property)}
 @item intangible
@@ -5307,10 +5318,15 @@ instead of the text that has the property.  These are called
 to interactively move point into the middle of buffer text that is
 replaced in this way.
 
+@cindex display properties, and invisible text
+@cindex composition property, and replacing display specs
   If a list of display specifications includes more than one replacing
 display specification, the first overrides the rest.  Replacing
 display specifications make most other display specifications
-irrelevant, since those don't apply to the replacement.
+irrelevant, since those don't apply to the replacement.  In addition,
+any @code{invisible} and @code{composition} properties of the text that
+is replaced are ignored, because the replaced text is skipped and its
+properties are not processed.
 
   For replacing display specifications, @dfn{the text that has the
 property} means all the consecutive characters that have the same